home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / cpp / cpp.rno < prev    next >
Text File  |  1992-04-13  |  9KB  |  307 lines
  1. .lm 8.rm 72.nhy
  2.  
  3. .no autosubtitle .style headers 3,0,0
  4. .pg.uc.ps 58,80.lm 8.rm 72
  5. .hd
  6. .hd mixed
  7. .head mixed
  8.  
  9. .st ########cpp#####C Pre-Processor
  10. .pg
  11. .hl 1 ^&C Pre-Processor\&
  12. .s 2
  13. .c ;*******
  14. .c ;* cpp *
  15. .c ;*******
  16. .s 2
  17. .lm +8
  18. .s.i -8;NAME:    cpp -- C Pre-Processor
  19. .s.f
  20. .i -8;SYNOPSIS:
  21. .s.nf
  22. cpp [-options] [infile [outfile]]
  23. .s.f
  24. .i -8;DESCRIPTION:
  25. .s
  26. CPP reads a C source file, expands macros and include
  27. files, and writes an input file for the C compiler.
  28. If no file arguments are given, CPP reads from stdin
  29. and writes to stdout.  If one file argument is given,
  30. it will define the input file, while two file arguments
  31. define both input and output files.  The file name "-"
  32. is a synonym for stdin or stdout as appropriate.
  33. .s
  34. The following options are supported.  Options may
  35. be given in either case.
  36. .lm +16
  37. .p -16
  38. -C        If set, source-file comments are written
  39. to the output file.  This allows the output of CPP to be
  40. used as the input to a program, such as lint, that expects
  41. commands embedded in specially-formatted comments.
  42. .p -16
  43. -Dname=value    Define the name as if the programmer wrote
  44. .s
  45. .nf
  46.     _#define name value
  47. .s
  48. .fill
  49. at the start of the first file.  If "=value" is not
  50. given, a value of "1" will be used.
  51. .s
  52. On non-unix systems, all alphabetic text will be forced
  53. to upper-case.
  54. .p -16
  55. -E        Always return "success" to the operating
  56. system, even if errors were detected.  Note that some fatal
  57. errors, such as a missing _#include file, will terminate
  58. CPP, returning "failure" even if the -E option is given.
  59. .p -16
  60. -Idirectory    Add this directory to the list of
  61. directories searched for _#include "..." and _#include <...>
  62. commands.  Note that there is no space between the
  63. "-I" and the directory string.  More than one -I command
  64. is permitted.  On non-Unix systems "directory" is forced
  65. to upper-case.
  66. .p -16
  67. -N        CPP normally predefines some symbols defining
  68. the target computer and operating system.  If -N is specified,
  69. no symbols will be predefined.  If -N -N is specified, the
  70. "always present" symbols, ____LINE____, ____FILE____, and ____DATE____
  71. are not defined.
  72. .p -16
  73. -Stext        CPP normally assumes that the size of
  74. the target computer's basic variable types is the same as the size
  75. of these types of the host computer.  (This can be overridden
  76. when CPP is compiled, however.)  The -S option allows dynamic
  77. respecification of these values.  "text" is a string of
  78. numbers, separated by commas, that specifies correct sizes.
  79. The sizes must be specified in the exact order:
  80. .s
  81. .nf
  82.     char short int long float double
  83. .s
  84. .fill
  85. If you specify the option as "-S*text", pointers to these
  86. types will be specified.  -S* takes one additional argument
  87. for pointer to function (e.g. int (*)())
  88. .s
  89. For example, to specify sizes appropriate for a PDP-11,
  90. you would write:
  91. .s
  92. .nf
  93.        c s i l f d func
  94.      -S1,2,2,2,4,8,
  95.     -S*2,2,2,2,2,2,2
  96. .s
  97. .fill
  98. Note that all values must be specified.
  99. .p -16
  100. -Uname        Undefine the name as if
  101. .s
  102. .nf
  103.     _#undef name
  104. .s
  105. .fill
  106. were given.  On non-Unix systems, "name" will be forced to
  107. upper-case.
  108. .p -16
  109. -Xnumber    Enable debugging code.  If no value is
  110. given, a value of 1 will be used.  (For maintenence of
  111. CPP only.)
  112. .s.lm -16
  113. .s
  114. .i -8;PRE-DEFINED VARIABLES:
  115. .s
  116. When CPP begins processing, the following variables will
  117. have been defined (unless the -N option is specified):
  118. .s
  119. Target computer (as appropriate):
  120. .s
  121. .nf
  122.     pdp11, vax, M68000 m68000 m68k
  123. .fill
  124. .s
  125. Target operating system (as appropriate):
  126. .s
  127. .nf
  128.     rsx, rt11, vms, unix
  129. .fill
  130. .s
  131. Target compiler (as appropriate):
  132. .s
  133. .nf
  134.     decus, vax11c
  135. .fill
  136. .s
  137. The implementor may add definitions to this list.
  138. The default definitions match the definition of the
  139. host computer, operating system, and C compiler.
  140. .s
  141. The following are always available unless undefined (or
  142. -N was specified twice):
  143. .lm +16
  144. .p -12
  145. ____FILE____    The input (or _#include) file being compiled
  146. (as a quoted string).
  147. .p -12
  148. ____LINE____    The line number being compiled.
  149. .p -12
  150. ____DATE____    The date of compilation as "Mmm dd yy"
  151. .p -12
  152. ____TIME____    The time of compilation as "hh:mm:ss"
  153. .p -12
  154. ____STDC____    The constant 1.
  155.  
  156. Thus,
  157. .s
  158. .nf
  159.     printf("Bug at line _%s,", ____LINE____);
  160.     printf(" source file _%s", ____FILE____);
  161.     printf(" compiled on _%s", ____DATE____);
  162. .fill
  163. .s.lm -16
  164. .s
  165. .i -8;DRAFT PROPOSED ANSI STANDARD CONSIDERATIONS:
  166. .s
  167. When CPP is itself compiled, many features of the Draft
  168. Proposed Standard that are incompatible with existing
  169. preprocessors may be disabled.  See the comments in CPP's
  170. source for details.
  171. .s
  172. Comments are removed from the input text.  The comment
  173. is replaced by a single space character.  The -C option
  174. preserves comments, writing them to the output file.
  175. .s
  176. The '$' character is considered to be a letter.  This is
  177. a permitted extension.
  178. .s
  179. The following new features of C are processed by CPP:
  180. .s.comment Note: significant spaces, not tabs, .br quotes #if, #elif
  181. .br;####_#elif expression    (_#else _#if)
  182. .br;####'_\xNNN'             (Hexadecimal constant)
  183. .br;####'_\a'                (Ascii BELL)
  184. .br;####'_\v'                (Ascii Vertical Tab)
  185. .br;####_#if defined NAME    1 if defined, 0 if not
  186. .br;####_#if defined (NAME)  1 if defined, 0 if not
  187. .br;####_#if sizeof (basic type)
  188. .br;####unary +
  189. .br;####123U, 123LU          Unsigned ints and longs.
  190. .br;####12.3L                Long double numbers
  191. .br;####token_##token        Token concatenation
  192. .br;####_#token              Token quoting
  193. .br;####_#include token      Expands to filename
  194. .br;####_#error tokens       Flags an error
  195. .s
  196. The Draft Proposed Standard has extended C, adding a constant
  197. string concatenation operator, where
  198. .s
  199. .nf
  200.     "foo" "bar"
  201. .s
  202. .fill
  203. is regarded as the single string "foobar".  (This does not
  204. affect CPP's processing but does permit a limited form of
  205. macro argument substitution into strings as will be discussed.)
  206. .s
  207. The Standard Committee plans to add token concatenation
  208. to #define command lines as follows:
  209. The sequence "Token1 ## Token2" is treated
  210. as if the programmer wrote "Token1Token2".  This could
  211. be used as follows:
  212. .s
  213. .nf
  214.     _#line 123
  215.     _#define ATLINE foo_##____LINE____
  216. .s
  217. .fill
  218. ATLINE would be defined as foo123.
  219. .s
  220. If the tokens T1 and T2 are concatenated into T3,
  221. this implementation operates as follows:
  222. .s
  223. .nf
  224.   1. Expand T1 if it is a macro.
  225.   2. Expand T2 if it is a macro.
  226.   3. Join the tokens, forming T3.
  227.   4. Expand T3 if it is a macro.
  228. .s
  229. .fill
  230. If a macro parameter is immediately proceeded by a #, string
  231. quotes (") are placed around the substituted parameter and
  232. a \ character is inserted before each " or \ character that
  233. appears surrounding,or inside a string literal or character
  234. constant in the argument.
  235. .s
  236. .nf
  237.     _#define VECSIZE 123
  238.     _#define vprint(name, size) _\
  239.       printf(#name "[" "size" "] = {_\n")
  240.       ... vprint(vector, VECSIZE);
  241. .s
  242. .fill
  243. expands (effectively) to
  244. .s
  245. .nf
  246.       vprint("vector[123] = {_\n");
  247. .s
  248. .fill
  249. Note that this will be useful if your C compiler supports
  250. the new string concatenation operation noted above.
  251. As implemented here, if you write
  252. .s
  253. .nf
  254.     _#define string(arg) "arg"
  255.       ... string("foo") ...
  256. .s
  257. .i -8;EXTENSIONS:
  258. .s
  259. .fill
  260. An extended macro facility is provided which allows and arbitrary unix
  261. process to act as a macro expander.  To define a macro do one of the
  262. following:
  263. .s
  264. #pragma defmacro name <file> options
  265. #pragma defmacro name "file" options
  266. .s
  267. .fill
  268. This provides a mapping between macro names and the file to be
  269. executed, which is on the include search path. "options" is zero or
  270.        more of the following: 
  271. recursive    - when present, the macro is recursively expanded
  272. delim=?      - the default delimiter of ; is replaced with ?
  273. other        - other options are passed as arguments to the
  274.            macro expander
  275. .s
  276. .fill
  277. When a "defmacro" style macro's name is found, the name and everything
  278. until the delimiter (includling all matching {} [] () <> "" '' and
  279. comments found along the way) is piped into the macro procedure's
  280. standard-input.  The procedure's standard output is scanned by CPP for
  281. further processing. The expansion replaces the macro call.
  282. number.
  283. .s
  284. .i -8;ERROR MESSAGES:
  285. .s
  286. Many.  CPP prints warning or error messages if you try to
  287. use multiple-byte character constants (non-transportable)
  288. if you _#undef a symbol that was not defined, or if your
  289. program has potentially nested comments.
  290. .s
  291. .i -8;AUTHORS:
  292. .s
  293. Martin Minow (Origional version)
  294. LaMott Oren  (Macro extensions and ANSI compatability)
  295. .s
  296. .i -8;BUGS:
  297. .s
  298. The _#if expression processor uses signed integers only.
  299. I.e, _#if 0xFFFFu < 0 may be TRUE.
  300. .s
  301. This program differs from the ANSI specification in that
  302. Trigraph sequences aren't implemented.
  303. .s
  304. .lm 8.rm 72.nhy
  305.  
  306.  
  307.